home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / gutenprint / vars.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-03-15  |  44.1 KB  |  1,388 lines
  1. /*
  2.  * "$id: vars.h,v 1.3.4.4 2004/03/09 03:00:25 rlk Exp $"
  3.  *
  4.  *   libgimpprint stp_vars_t core functions.
  5.  *
  6.  *   Copyright 1997-2000 Michael Sweet (mike@easysw.com) and
  7.  *    Robert Krawitz (rlk@alum.mit.edu)
  8.  *
  9.  *   This program is free software; you can redistribute it and/or modify it
  10.  *   under the terms of the GNU General Public License as published by the Free
  11.  *   Software Foundation; either version 2 of the License, or (at your option)
  12.  *   any later version.
  13.  *
  14.  *   This program is distributed in the hope that it will be useful, but
  15.  *   WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  16.  *   or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  17.  *   for more details.
  18.  *
  19.  *   You should have received a copy of the GNU General Public License
  20.  *   along with this program; if not, write to the Free Software
  21.  *   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  22.  */
  23.  
  24. /**
  25.  * @file gutenprint/vars.h
  26.  * @brief Print job functions.
  27.  */
  28.  
  29. #ifndef GUTENPRINT_VARS_H
  30. #define GUTENPRINT_VARS_H
  31.  
  32. #include <gutenprint/array.h>
  33. #include <gutenprint/curve.h>
  34. #include <gutenprint/string-list.h>
  35.  
  36. #ifdef __cplusplus
  37. extern "C" {
  38. #endif
  39.  
  40. /**
  41.  * The vars data type contains all the information about a print job,
  42.  * this includes information such as the printer model, paper size,
  43.  * print resolution etc.  Most of these job options are expressed as
  44.  * parameters which vary according to the model and other options
  45.  * selected.
  46.  *
  47.  * The representation of printer settings has changed dramatically from 4.2.
  48.  * All (well most, anyway) settings outside of basics such as the printer
  49.  * model and sizing settings are now typed parameters.
  50.  *
  51.  * @defgroup vars vars
  52.  * @{
  53.  */
  54.  
  55. struct stp_vars;
  56. /** The vars opaque data type. */
  57. typedef struct stp_vars stp_vars_t;
  58.  
  59. /**
  60.  * Parameter types.
  61.  * The following types are permitted for a printer setting.  Not all
  62.  * are currently implemented.
  63.  */
  64. typedef enum
  65. {
  66.   STP_PARAMETER_TYPE_STRING_LIST, /*!< Single string choice from a list. */
  67.   STP_PARAMETER_TYPE_INT,    /*!< Integer. */
  68.   STP_PARAMETER_TYPE_BOOLEAN,    /*!< Boolean. */
  69.   STP_PARAMETER_TYPE_DOUBLE,    /*!< Floating point number. */
  70.   STP_PARAMETER_TYPE_CURVE,    /*!< Curve. */
  71.   STP_PARAMETER_TYPE_FILE,    /*!< Filename (NYI, need to consider security). */
  72.   STP_PARAMETER_TYPE_RAW,    /*!< Raw, opaque data. */
  73.   STP_PARAMETER_TYPE_ARRAY,     /*!< Array. */
  74.   STP_PARAMETER_TYPE_DIMENSION, /*!< Linear dimension. */
  75.   STP_PARAMETER_TYPE_INVALID    /*!< Invalid type (should never be used). */
  76. } stp_parameter_type_t;
  77.  
  78. /**
  79.  * Parameter class.
  80.  * What kind of setting this is, for the purpose of user interface
  81.  * representation.
  82.  */
  83. typedef enum
  84. {
  85.   STP_PARAMETER_CLASS_FEATURE,    /*!< Printer feature. */
  86.   STP_PARAMETER_CLASS_OUTPUT,    /*!< Output control. */
  87.   STP_PARAMETER_CLASS_CORE,    /*!< Core Gimp-Print parameter. */
  88.   STP_PARAMETER_CLASS_INVALID   /*!< Invalid class (should never be used). */
  89. } stp_parameter_class_t;
  90.  
  91. /**
  92.  * Parameter level.
  93.  * What "level" a setting is at, for UI design.
  94.  */
  95. typedef enum
  96. {
  97.   STP_PARAMETER_LEVEL_BASIC,     /*!< Basic parameter, shown by all UIs. */
  98.   STP_PARAMETER_LEVEL_ADVANCED,  /*!< Advanced parameter, shown by advanced UIs. */
  99.   STP_PARAMETER_LEVEL_ADVANCED1, /*!< Advanced1 parameter, shown by advanced UIs. */
  100.   STP_PARAMETER_LEVEL_ADVANCED2, /*!< Advanced2 parameter, shown by advanced UIs. */
  101.   STP_PARAMETER_LEVEL_ADVANCED3, /*!< Advanced3 parameter, shown by advanced UIs. */
  102.   STP_PARAMETER_LEVEL_ADVANCED4, /*!< Advanced4 parameter, shown by advanced UIs. */
  103.   STP_PARAMETER_LEVEL_INTERNAL,     /*!< Parameters used only within Gimp-Print. */
  104.   STP_PARAMETER_LEVEL_EXTERNAL,     /*!< Parameters used only outside Gimp-Print. */
  105.   STP_PARAMETER_LEVEL_INVALID    /*!< Invalid level (should never be used). */
  106. } stp_parameter_level_t;
  107.  
  108. /**
  109.  * Parameter activity.
  110.  * Whether a parameter is currently active (i. e. whether its value
  111.  * should be used by the driver or not).  All parameters default to being
  112.  * active unless explicitly "turned off".
  113.  */
  114. typedef enum
  115. {
  116.   STP_PARAMETER_INACTIVE,  /*!< Parameter is inactive (unused). */
  117.   STP_PARAMETER_DEFAULTED, /*!< Parameter is set to its default value. */
  118.   STP_PARAMETER_ACTIVE     /*!< Parameter is active (used). */
  119. } stp_parameter_activity_t;
  120.  
  121. /*
  122.  * Other parameter types
  123.  */
  124.  
  125. /** Raw parameter. */
  126. typedef struct
  127. {
  128.   size_t bytes;     /*!< Size of data. */
  129.   const void *data; /*!< Raw data. */
  130. } stp_raw_t;
  131.  
  132. #define STP_RAW(x) { sizeof((x)), (x) }
  133. #define STP_RAW_STRING(x) { sizeof((x)) - 1, (x) }
  134.  
  135. /** double_bound (range) parameter. */
  136. typedef struct
  137. {
  138.   double lower; /*!< Lower bound. */
  139.   double upper; /*!< Upper bound. */
  140. } stp_double_bound_t;
  141.  
  142. /** int_bound (range) parameter. */
  143. typedef struct
  144. {
  145.   int lower; /*!< Lower bound. */
  146.   int upper; /*!< Upper bound. */
  147. } stp_int_bound_t;
  148.  
  149. /** Parameter description. */
  150. typedef struct
  151. {
  152.   const char *name;         /*!< Internal name (key). */
  153.   const char *text;         /*!< User-visible name. */
  154.   const char *category;         /*!< User-visible category name. */
  155.   const char *help;         /*!< Help string. */
  156.   stp_parameter_type_t p_type;   /*!< Parameter type. */
  157.   stp_parameter_class_t p_class; /*!< Parameter class. */
  158.   stp_parameter_level_t p_level; /*!< Parameter level. */
  159.   unsigned char is_mandatory;    /*!< The parameter is required, even when set inactive. */
  160.   unsigned char is_active;       /*!< Is the parameter active? */
  161.   unsigned char channel;         /*!< The channel to which this parameter applies */
  162.   unsigned char verify_this_parameter;     /*!< Should the verify system check this parameter? */
  163.   unsigned char read_only;
  164.   union
  165.   {
  166.     stp_curve_t *curve;       /*!< curve parameter value. */
  167.     stp_double_bound_t dbl;  /*!< double_bound parameter value. */
  168.     stp_int_bound_t integer; /*!< int_bound parameter value. */
  169.     stp_int_bound_t dimension; /*!< int_bound parameter value. */
  170.     stp_string_list_t *str;   /*!< string_list parameter value. */
  171.     stp_array_t *array;      /*!< array parameter value. */
  172.   } bounds; /*!< Limits on the values the parameter may take. */
  173.   union
  174.   {
  175.     stp_curve_t *curve; /*!< Default curve parameter value. */
  176.     double dbl;         /*!< Default double parameter value. */
  177.     int dimension;      /*!< Default dimension parameter value. */
  178.     int integer;        /*!< Default int parameter value. */
  179.     int boolean;        /*!< Default boolean parameter value. */
  180.     const char *str;    /*!< Default string parameter value. */
  181.     stp_array_t *array; /*!< Default array parameter value. */
  182.   } deflt; /*!< Default value of the parameter. */
  183. } stp_parameter_t;
  184.  
  185. /** The parameter_list opaque data type. */
  186. typedef void *stp_parameter_list_t;
  187. /** The constant parameter_list opaque data type. */
  188. typedef const void *stp_const_parameter_list_t;
  189.  
  190. /**
  191.  * Output function supplied by the calling application.
  192.  * There are two output functions supplied by the caller, one to send
  193.  * output data and one to report errors.
  194.  * @param data a pointer to an opaque object owned by the calling
  195.  *             application.
  196.  * @param buffer the data to output.
  197.  * @param bytes the size of buffer (in bytes).
  198.  */
  199. typedef void (*stp_outfunc_t) (void *data, const char *buffer, size_t bytes);
  200.  
  201.  
  202. /****************************************************************
  203. *                                                               *
  204. * BASIC PRINTER SETTINGS                                        *
  205. *                                                               *
  206. ****************************************************************/
  207.  
  208. /**
  209.  * Create a new vars object.
  210.  * @returns the newly created vars object.
  211.  */
  212. extern stp_vars_t *stp_vars_create(void);
  213.  
  214. /**
  215.  * Copy a vars object.
  216.  * Both dest and source must be valid vars objects previously
  217.  * created with stp_vars_create().
  218.  * @param dest the destination vars.
  219.  * @param source the source vars.
  220.  */
  221. extern void stp_vars_copy(stp_vars_t *dest, const stp_vars_t *source);
  222.  
  223. /**
  224.  * Copy and allocate a vars object.
  225.  * source must be a valid vars object previously created with
  226.  * stp_vars_create().
  227.  * @param source the source vars.
  228.  * @returns the new copy of the vars.
  229.  */
  230. extern stp_vars_t *stp_vars_create_copy(const stp_vars_t *source);
  231.  
  232. /**
  233.  * Destroy a vars object.
  234.  * It is an error to destroy the vars more than once.
  235.  * @param v the vars to destroy.
  236.  */
  237. extern void stp_vars_destroy(stp_vars_t *v);
  238.  
  239. /**
  240.  * Set the name of the printer driver.
  241.  * @param v the vars to use.
  242.  * @param val the name to set.
  243.  */
  244. extern void stp_set_driver(stp_vars_t *v, const char *val);
  245.  
  246. /**
  247.  * Set the name of the printer driver.
  248.  * @param v the vars to use.
  249.  * @param val the name to set.
  250.  * @param bytes the length of val (in bytes).
  251.  */
  252. extern void stp_set_driver_n(stp_vars_t *v, const char *val, int bytes);
  253.  
  254. /**
  255.  * Get the name of the printer driver.
  256.  * @returns the name of the printer driver (must not be freed).
  257.  */
  258. extern const char *stp_get_driver(const stp_vars_t *v);
  259.  
  260. /**
  261.  * Set the name of the color conversion routine, if not the default.
  262.  * @param v the vars to use.
  263.  * @param val the name to set.
  264.  */
  265. extern void stp_set_color_conversion(stp_vars_t *v, const char *val);
  266.  
  267. /**
  268.  * Set the name of the color conversion routine, if not the default.
  269.  * @param v the vars to use.
  270.  * @param val the name to set.
  271.  * @param bytes the length of val (in bytes).
  272.  */
  273. extern void stp_set_color_conversion_n(stp_vars_t *v, const char *val, int bytes);
  274.  
  275. /**
  276.  * Get the name of the color conversion routine.
  277.  * @returns the name of the color conversion routine (must not be freed).
  278.  */
  279. extern const char *stp_get_color_conversion(const stp_vars_t *v);
  280.  
  281. /*
  282.  * Set/get the position and size of the image
  283.  */
  284.  
  285. /**
  286.  * Set the left edge of the image.
  287.  * @param v the vars to use.
  288.  * @param val the value to set.
  289.  */
  290. extern void stp_set_left(stp_vars_t *v, int val);
  291.  
  292. /**
  293.  * Get the left edge of the image.
  294.  * @returns the left edge.
  295.  */
  296. extern int stp_get_left(const stp_vars_t *v);
  297.  
  298. /**
  299.  * Set the top edge of the image.
  300.  * @param v the vars to use.
  301.  * @param val the value to set.
  302.  */
  303. extern void stp_set_top(stp_vars_t *v, int val);
  304.  
  305. /**
  306.  * Get the top edge of the image.
  307.  * @returns the left edge.
  308.  */
  309. extern int stp_get_top(const stp_vars_t *v);
  310.  
  311. /**
  312.  * Set the width of the image.
  313.  * @param v the vars to use.
  314.  * @param val the value to set.
  315.  */
  316. extern void stp_set_width(stp_vars_t *v, int val);
  317.  
  318. /**
  319.  * Get the width edge of the image.
  320.  * @returns the left edge.
  321.  */
  322. extern int stp_get_width(const stp_vars_t *v);
  323.  
  324. /**
  325.  * Set the height of the image.
  326.  * @param v the vars to use.
  327.  * @param val the value to set.
  328.  */
  329. extern void stp_set_height(stp_vars_t *v, int val);
  330.  
  331. /**
  332.  * Get the height of the image.
  333.  * @returns the left edge.
  334.  */
  335. extern int stp_get_height(const stp_vars_t *v);
  336.  
  337. /*
  338.  * For custom page widths, these functions may be used.
  339.  */
  340.  
  341. /**
  342.  * Set the page width.
  343.  * @param v the vars to use.
  344.  * @param val the value to set.
  345.  */
  346. extern void stp_set_page_width(stp_vars_t *v, int val);
  347.  
  348. /**
  349.  * Get the page width.
  350.  * @returns the page width.
  351.  */
  352. extern int stp_get_page_width(const stp_vars_t *v);
  353.  
  354. /**
  355.  * Set the page height.
  356.  * @param v the vars to use.
  357.  * @param val the value to set.
  358.  */
  359. extern void stp_set_page_height(stp_vars_t *v, int val);
  360.  
  361. /**
  362.  * Get the page height.
  363.  * @returns the page height.
  364.  */
  365. extern int stp_get_page_height(const stp_vars_t *v);
  366.  
  367. /**
  368.  * Set the function used to print output information.
  369.  * These must be supplied by the caller.  outdata is passed as an
  370.  * arguments to outfunc; typically it will be a file descriptor.
  371.  * @param v the vars to use.
  372.  * @param val the value to set.
  373.  */
  374. extern void stp_set_outfunc(stp_vars_t *v, stp_outfunc_t val);
  375.  
  376. /**
  377.  * Get the function used to print output information.
  378.  * @param v the vars to use.
  379.  * @returns the outfunc.
  380.  */
  381. extern stp_outfunc_t stp_get_outfunc(const stp_vars_t *v);
  382.  
  383. /**
  384.  * Set the function used to print error and diagnostic information.
  385.  * These must be supplied by the caller.  errdata is passed as an
  386.  * arguments to errfunc; typically it will be a file descriptor.
  387.  * @param v the vars to use.
  388.  * @param val the value to set.
  389.  */
  390. extern void stp_set_errfunc(stp_vars_t *v, stp_outfunc_t val);
  391.  
  392. /**
  393.  * Get the function used to print output information.
  394.  * @param v the vars to use.
  395.  * @returns the outfunc.
  396.  */
  397. extern stp_outfunc_t stp_get_errfunc(const stp_vars_t *v);
  398.  
  399. /**
  400.  * Set the output data.
  401.  * @param v the vars to use.
  402.  * @param val the output data.  This will typically be a file
  403.  * descriptor, but it is entirely up to the caller exactly what type
  404.  * this might be.
  405.  */
  406. extern void stp_set_outdata(stp_vars_t *v, void *val);
  407.  
  408. /**
  409.  * Get the output data.
  410.  * @param v the vars to use.
  411.  * @returns the output data.
  412.  */
  413. extern void *stp_get_outdata(const stp_vars_t *v);
  414.  
  415. /**
  416.  * Set the error data.
  417.  * @param v the vars to use.
  418.  * @param val the error data.  This will typically be a file
  419.  * descriptor, but it is entirely up to the caller exactly what type
  420.  * this might be.
  421.  */
  422. extern void stp_set_errdata(stp_vars_t *v, void *val);
  423.  
  424. /**
  425.  * Get the error data.
  426.  * @param v the vars to use.
  427.  * @returns the output data.
  428.  */
  429. extern void *stp_get_errdata(const stp_vars_t *v);
  430.  
  431. /**
  432.  * Merge defaults for a printer with user-chosen settings.
  433.  * @deprecated This is likely to go away.
  434.  * @param user the destination vars.
  435.  * @param print the vars to merge into user.
  436.  */
  437. extern void stp_merge_printvars(stp_vars_t *user, const stp_vars_t *print);
  438.  
  439.  
  440. /****************************************************************
  441. *                                                               *
  442. * PARAMETER MANAGEMENT                                          *
  443. *                                                               *
  444. ****************************************************************/
  445.  
  446. /**
  447.  * List the available parameters for the currently chosen settings.
  448.  * This does not fill in the bounds and defaults; it merely provides
  449.  * a list of settings.  To fill in detailed information for a setting,
  450.  * use stp_describe_parameter.
  451.  * @param v the vars to use.
  452.  * @returns a list of available parameters (must be freed with
  453.  * stp_parameter_list_destroy()).
  454.  */
  455. extern stp_parameter_list_t stp_get_parameter_list(const stp_vars_t *v);
  456.  
  457. /**
  458.  * List the number of available parameters for the currently chosen
  459.  * settings.
  460.  * @param list the parameter_list to use.
  461.  * @returns the number of parameters.
  462.  */
  463. extern size_t stp_parameter_list_count(stp_const_parameter_list_t list);
  464.  
  465. /**
  466.  * Find a parameter by its name.
  467.  * @param list the parameter_list to use.
  468.  * @param name the name of the parameter.
  469.  * @returns a pointer to the parameter (must not be freed), or NULL if
  470.  * no parameter was found.
  471.  */
  472. extern const stp_parameter_t *
  473. stp_parameter_find(stp_const_parameter_list_t list, const char *name);
  474.  
  475. /**
  476.  * Find a parameter by its index number.
  477.  * @param list the parameter_list to use.
  478.  * @param item the index number of the parameter (must not be greater
  479.  * than stp_parameter_list_count - 1).
  480.  * @returns a pointer to the parameter (must not be freed), or NULL if
  481.  * no parameter was found.
  482.  */
  483. extern const stp_parameter_t *
  484. stp_parameter_list_param(stp_const_parameter_list_t list, size_t item);
  485.  
  486. /**
  487.  * Destroy a parameter_list.
  488.  * It is an error to destroy the parameter_list more than once.
  489.  * @param list the parameter_list to destroy.
  490.  */
  491. extern void stp_parameter_list_destroy(stp_parameter_list_t list);
  492.  
  493. /**
  494.  * Create a parameter_list.
  495.  * @returns the newly created parameter_list.
  496.  */
  497. extern stp_parameter_list_t stp_parameter_list_create(void);
  498.  
  499. /**
  500.  * Add a parameter to a parameter_list.
  501.  * @param list the parameter_list to use.
  502.  * @param item the parameter to add.
  503.  */
  504. extern void stp_parameter_list_add_param(stp_parameter_list_t list,
  505.                      const stp_parameter_t *item);
  506.  
  507. /**
  508.  * Copy and allocate a parameter_list.
  509.  * A new parameter_list will be created, and then the contents of
  510.  * source will be
  511.  * copied into it.
  512.  * @param list the source parameter_list.
  513.  * @returns the new copy of the parameter_list.
  514.  */
  515. extern stp_parameter_list_t
  516. stp_parameter_list_copy(stp_const_parameter_list_t list);
  517.  
  518. /**
  519.  * Append one parameter_list to another.
  520.  * @param list the destination list (to append to).
  521.  * @param append the list of paramters to append.  Each item that does
  522.  * not already exist in list will be appended.
  523.  */
  524. extern void
  525. stp_parameter_list_append(stp_parameter_list_t list,
  526.               stp_const_parameter_list_t append);
  527.  
  528. /**
  529.  * Describe a parameter in detail.
  530.  * All of the parameter fields will be populated.
  531.  * @param v the vars to use.
  532.  * @param name the name of the parameter.
  533.  * @param description a pointer to an stp_parameter_t to store the
  534.  * parameter description in.
  535.  */
  536. extern void
  537. stp_describe_parameter(const stp_vars_t *v, const char *name,
  538.                stp_parameter_t *description);
  539.  
  540. /**
  541.  * Destroy a parameter description.
  542.  * This must be called even if the stp_parameter_t was not allocated
  543.  * with malloc, since some members are dynamically allocated.
  544.  * @param description the parameter description to destroy.
  545.  */
  546. extern void stp_parameter_description_destroy(stp_parameter_t *description);
  547.  
  548. /**
  549.  * Find a parameter by its name from a vars object.
  550.  * @param v the vars to use.
  551.  * @param name the name of the parameter.
  552.  * @returns a pointer to the parameter (must not be freed), or NULL if
  553.  * no parameter was found.
  554.  */
  555. extern const stp_parameter_t *
  556. stp_parameter_find_in_settings(const stp_vars_t *v, const char *name);
  557.  
  558. /**
  559.  * Set a string parameter.
  560.  * @param v the vars to use.
  561.  * @param parameter the name of the parameter.
  562.  * @param value the value to set.
  563.  */
  564. extern void stp_set_string_parameter(stp_vars_t *v, const char *parameter,
  565.                      const char *value);
  566.  
  567. /**
  568.  * Set a string parameter.
  569.  * @param v the vars to use.
  570.  * @param parameter the name of the parameter.
  571.  * @param value the value to set (must not contain NUL).
  572.  * @param bytes the length of value (in bytes).
  573.  */
  574. extern void stp_set_string_parameter_n(stp_vars_t *v, const char *parameter,
  575.                        const char *value, size_t bytes);
  576.  
  577. /**
  578.  * Set a file parameter.
  579.  * @param v the vars to use.
  580.  * @param parameter the name of the parameter.
  581.  * @param value the value to set.
  582.  */
  583. extern void stp_set_file_parameter(stp_vars_t *v, const char *parameter,
  584.                    const char *value);
  585.  
  586. /**
  587.  * Set a file parameter.
  588.  * @param v the vars to use.
  589.  * @param parameter the name of the parameter.
  590.  * @param value the value to set (must not contain NUL).
  591.  * @param bytes the length of value (in bytes).
  592.  */
  593. extern void stp_set_file_parameter_n(stp_vars_t *v, const char *parameter,
  594.                      const char *value, size_t bytes);
  595.  
  596. /**
  597.  * Set a float parameter.
  598.  * @param v the vars to use.
  599.  * @param parameter the name of the parameter.
  600.  * @param value the value to set.
  601.  */
  602. extern void stp_set_float_parameter(stp_vars_t *v, const char *parameter,
  603.                     double value);
  604.  
  605. /**
  606.  * Set an integer parameter.
  607.  * @param v the vars to use.
  608.  * @param parameter the name of the parameter.
  609.  * @param value the value to set.
  610.  */
  611. extern void stp_set_int_parameter(stp_vars_t *v, const char *parameter,
  612.                   int value);
  613.  
  614. /**
  615.  * Set a dimension parameter.
  616.  * @param v the vars to use.
  617.  * @param parameter the name of the parameter.
  618.  * @param value the value to set.
  619.  */
  620. extern void stp_set_dimension_parameter(stp_vars_t *v, const char *parameter,
  621.                     int value);
  622.  
  623. /**
  624.  * Set a boolean parameter.
  625.  * @param v the vars to use.
  626.  * @param parameter the name of the parameter.
  627.  * @param value the value to set.
  628.  */
  629. extern void stp_set_boolean_parameter(stp_vars_t *v, const char *parameter,
  630.                       int value);
  631.  
  632. /**
  633.  * Set a curve parameter.
  634.  * @param v the vars to use.
  635.  * @param parameter the name of the parameter.
  636.  * @param value the value to set.
  637.  */
  638. extern void stp_set_curve_parameter(stp_vars_t *v, const char *parameter,
  639.                     const stp_curve_t *value);
  640.  
  641. /**
  642.  * Set an array parameter.
  643.  * @param v the vars to use.
  644.  * @param parameter the name of the parameter.
  645.  * @param value the value to set.
  646.  */
  647. extern void stp_set_array_parameter(stp_vars_t *v, const char *parameter,
  648.                     const stp_array_t *value);
  649.  
  650. /**
  651.  * Set a raw parameter.
  652.  * @param v the vars to use.
  653.  * @param parameter the name of the parameter.
  654.  * @param value the value to set.
  655.  * @param bytes the length of value (in bytes).
  656.  */
  657. extern void stp_set_raw_parameter(stp_vars_t *v, const char *parameter,
  658.                   const void *value, size_t bytes);
  659.  
  660. /**
  661.  * Multiply the value of a float parameter by a scaling factor.
  662.  * @param v the vars to use.
  663.  * @param parameter the name of the parameter.
  664.  * @param scale the factor to multiply the value by.
  665.  */
  666. extern void stp_scale_float_parameter(stp_vars_t *v, const char *parameter,
  667.                       double scale);
  668.  
  669. /**
  670.  * Set a default string parameter.
  671.  * The value is set if the parameter is not already set.  This avoids
  672.  * having to check if the parameter is set prior to setting it, if you
  673.  * do not want to override the existing value.
  674.  * @param v the vars to use.
  675.  * @param parameter the name of the parameter.
  676.  * @param value the value to set.
  677.  */
  678. extern void stp_set_default_string_parameter(stp_vars_t *v,
  679.                          const char *parameter,
  680.                          const char *value);
  681.  
  682. /**
  683.  * Set a default string parameter.
  684.  * The value is set if the parameter is not already set.  This avoids
  685.  * having to check if the parameter is set prior to setting it, if you
  686.  * do not want to override the existing value.
  687.  * @param v the vars to use.
  688.  * @param parameter the name of the parameter.
  689.  * @param value the value to set (must not contain NUL).
  690.  * @param bytes the length of value (in bytes).
  691.  */
  692. extern void stp_set_default_string_parameter_n(stp_vars_t *v,
  693.                            const char *parameter,
  694.                            const char *value, size_t bytes);
  695.  
  696. /**
  697.  * Set a default file parameter.
  698.  * The value is set if the parameter is not already set.  This avoids
  699.  * having to check if the parameter is set prior to setting it, if you
  700.  * do not want to override the existing value.
  701.  * @param v the vars to use.
  702.  * @param parameter the name of the parameter.
  703.  * @param value the value to set.
  704.  */
  705. extern void stp_set_default_file_parameter(stp_vars_t *v,
  706.                        const char *parameter,
  707.                        const char *value);
  708.  
  709. /**
  710.  * Set a default file parameter.
  711.  * The value is set if the parameter is not already set.  This avoids
  712.  * having to check if the parameter is set prior to setting it, if you
  713.  * do not want to override the existing value.
  714.  * @param v the vars to use.
  715.  * @param parameter the name of the parameter.
  716.  * @param value the value to set (must not contain NUL).
  717.  * @param bytes the length of value (in bytes).
  718.  */
  719. extern void stp_set_default_file_parameter_n(stp_vars_t *v,
  720.                          const char *parameter,
  721.                          const char *value, size_t bytes);
  722.  
  723. /**
  724.  * Set a default float parameter.
  725.  * The value is set if the parameter is not already set.  This avoids
  726.  * having to check if the parameter is set prior to setting it, if you
  727.  * do not want to override the existing value.
  728.  * @param v the vars to use.
  729.  * @param parameter the name of the parameter.
  730.  * @param value the value to set.
  731.  */
  732. extern void stp_set_default_float_parameter(stp_vars_t *v,
  733.                         const char *parameter,
  734.                         double value);
  735.  
  736. /**
  737.  * Set a default integer parameter.
  738.  * The value is set if the parameter is not already set.  This avoids
  739.  * having to check if the parameter is set prior to setting it, if you
  740.  * do not want to override the existing value.
  741.  * @param v the vars to use.
  742.  * @param parameter the name of the parameter.
  743.  * @param value the value to set.
  744.  */
  745. extern void stp_set_default_int_parameter(stp_vars_t *v,
  746.                       const char *parameter,
  747.                       int value);
  748.  
  749. /**
  750.  * Set a default dimension parameter.
  751.  * The value is set if the parameter is not already set.  This avoids
  752.  * having to check if the parameter is set prior to setting it, if you
  753.  * do not want to override the existing value.
  754.  * @param v the vars to use.
  755.  * @param parameter the name of the parameter.
  756.  * @param value the value to set.
  757.  */
  758. extern void stp_set_default_dimension_parameter(stp_vars_t *v,
  759.                         const char *parameter,
  760.                         int value);
  761.  
  762. /**
  763.  * Set a default boolean parameter.
  764.  * The value is set if the parameter is not already set.  This avoids
  765.  * having to check if the parameter is set prior to setting it, if you
  766.  * do not want to override the existing value.
  767.  * @param v the vars to use.
  768.  * @param parameter the name of the parameter.
  769.  * @param value the value to set.
  770.  */
  771. extern void stp_set_default_boolean_parameter(stp_vars_t *v,
  772.                           const char *parameter,
  773.                           int value);
  774.  
  775. /**
  776.  * Set a default curve parameter.
  777.  * The value is set if the parameter is not already set.  This avoids
  778.  * having to check if the parameter is set prior to setting it, if you
  779.  * do not want to override the existing value.
  780.  * @param v the vars to use.
  781.  * @param parameter the name of the parameter.
  782.  * @param value the value to set.
  783.  */
  784. extern void stp_set_default_curve_parameter(stp_vars_t *v,
  785.                         const char *parameter,
  786.                         const stp_curve_t *value);
  787.  
  788. /**
  789.  * Set a default array parameter.
  790.  * The value is set if the parameter is not already set.  This avoids
  791.  * having to check if the parameter is set prior to setting it, if you
  792.  * do not want to override the existing value.
  793.  * @param v the vars to use.
  794.  * @param parameter the name of the parameter.
  795.  * @param value the value to set.
  796.  */
  797. extern void stp_set_default_array_parameter(stp_vars_t *v,
  798.                         const char *parameter,
  799.                         const stp_array_t *value);
  800.  
  801. /**
  802.  * Set a default raw parameter.
  803.  * The value is set if the parameter is not already set.  This avoids
  804.  * having to check if the parameter is set prior to setting it, if you
  805.  * do not want to override the existing value.
  806.  * @param v the vars to use.
  807.  * @param parameter the name of the parameter.
  808.  * @param value the value to set.
  809.  * @param bytes the length of value (in bytes).
  810.  */
  811. extern void stp_set_default_raw_parameter(stp_vars_t *v,
  812.                       const char *parameter,
  813.                       const void *value, size_t bytes);
  814.  
  815. /**
  816.  * Get a string parameter.
  817.  * @param v the vars to use.
  818.  * @param parameter the name of the parameter.
  819.  * @returns the string, or NULL if no parameter was found.
  820.  */
  821. extern const char *stp_get_string_parameter(const stp_vars_t *v,
  822.                         const char *parameter);
  823.  
  824. /**
  825.  * Get a file parameter.
  826.  * @param v the vars to use.
  827.  * @param parameter the name of the parameter.
  828.  * @returns the filename, or NULL if no parameter was found.
  829.  */
  830. extern const char *stp_get_file_parameter(const stp_vars_t *v,
  831.                       const char *parameter);
  832.  
  833. /**
  834.  * Get a float parameter.
  835.  * @param v the vars to use.
  836.  * @param parameter the name of the parameter.
  837.  * @returns the float value.
  838.  */
  839. extern double stp_get_float_parameter(const stp_vars_t *v,
  840.                         const char *parameter);
  841.  
  842. /**
  843.  * Get an integer parameter.
  844.  * @param v the vars to use.
  845.  * @param parameter the name of the parameter.
  846.  * @returns the integer value.
  847.  */
  848. extern int stp_get_int_parameter(const stp_vars_t *v,
  849.                  const char *parameter);
  850.  
  851. /**
  852.  * Get a dimension parameter.
  853.  * @param v the vars to use.
  854.  * @param parameter the name of the parameter.
  855.  * @returns the dimension (integer) value.
  856.  */
  857. extern int stp_get_dimension_parameter(const stp_vars_t *v,
  858.                        const char *parameter);
  859.  
  860. /**
  861.  * Get a boolean parameter.
  862.  * @param v the vars to use.
  863.  * @param parameter the name of the parameter.
  864.  * @returns the boolean value.
  865.  */
  866. extern int stp_get_boolean_parameter(const stp_vars_t *v,
  867.                      const char *parameter);
  868.  
  869. /**
  870.  * Get a curve parameter.
  871.  * @param v the vars to use.
  872.  * @param parameter the name of the parameter.
  873.  * @returns the curve, or NULL if no parameter was found.
  874.  */
  875. extern const stp_curve_t *stp_get_curve_parameter(const stp_vars_t *v,
  876.                           const char *parameter);
  877.  
  878. /**
  879.  * Get an array parameter.
  880.  * @param v the vars to use.
  881.  * @param parameter the name of the parameter.
  882.  * @returns the array, or NULL if no parameter was found.
  883.  */
  884. extern const stp_array_t *stp_get_array_parameter(const stp_vars_t *v,
  885.                           const char *parameter);
  886.  
  887. /**
  888.  * Get a raw parameter.
  889.  * @param v the vars to use.
  890.  * @param parameter the name of the parameter.
  891.  * @returns the raw data, or NULL if no parameter was found.
  892.  */
  893. extern const stp_raw_t *stp_get_raw_parameter(const stp_vars_t *v,
  894.                           const char *parameter);
  895.  
  896. /**
  897.  * Clear a string parameter.
  898.  * The parameter is set to NULL.
  899.  * @param v the vars to use.
  900.  * @param parameter the name of the parameter.
  901.  */
  902. extern void stp_clear_string_parameter(stp_vars_t *v, const char *parameter);
  903.  
  904. /**
  905.  * Clear a file parameter.
  906.  * The parameter is set to NULL.
  907.  * @param v the vars to use.
  908.  * @param parameter the name of the parameter.
  909.  */
  910. extern void stp_clear_file_parameter(stp_vars_t *v, const char *parameter);
  911.  
  912. /**
  913.  * Clear (remove) a float parameter.
  914.  * @param v the vars to use.
  915.  * @param parameter the name of the parameter.
  916.  */
  917. extern void stp_clear_float_parameter(stp_vars_t *v, const char *parameter);
  918.  
  919. /**
  920.  * Clear (remove) an integer parameter.
  921.  * @param v the vars to use.
  922.  * @param parameter the name of the parameter.
  923.  */
  924. extern void stp_clear_int_parameter(stp_vars_t *v, const char *parameter);
  925.  
  926. /**
  927.  * Clear (remove) a dimension parameter.
  928.  * @param v the vars to use.
  929.  * @param parameter the name of the parameter.
  930.  */
  931. extern void stp_clear_dimension_parameter(stp_vars_t *v, const char *parameter);
  932.  
  933. /**
  934.  * Clear (remove) a boolean parameter.
  935.  * @param v the vars to use.
  936.  * @param parameter the name of the parameter.
  937.  */
  938. extern void stp_clear_boolean_parameter(stp_vars_t *v, const char *parameter);
  939.  
  940. /**
  941.  * Clear a curve parameter.
  942.  * The parameter is set to NULL.
  943.  * @param v the vars to use.
  944.  * @param parameter the name of the parameter.
  945.  */
  946. extern void stp_clear_curve_parameter(stp_vars_t *v, const char *parameter);
  947.  
  948. /**
  949.  * Clear an array parameter.
  950.  * The parameter is set to NULL.
  951.  * @param v the vars to use.
  952.  * @param parameter the name of the parameter.
  953.  */
  954. extern void stp_clear_array_parameter(stp_vars_t *v, const char *parameter);
  955.  
  956. /**
  957.  * Clear a raw parameter.
  958.  * The parameter is set to NULL.
  959.  * @param v the vars to use.
  960.  * @param parameter the name of the parameter.
  961.  */
  962. extern void stp_clear_raw_parameter(stp_vars_t *v, const char *parameter);
  963.  
  964. /**
  965.  * Set the activity of a string parameter.
  966.  * @param v the vars to use.
  967.  * @param parameter the name of the parameter.
  968.  * @param active the activity status to set (should be set to
  969.  * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).
  970.  */
  971. extern void stp_set_string_parameter_active(const stp_vars_t *v,
  972.                         const char *parameter,
  973.                         stp_parameter_activity_t active);
  974.  
  975. /**
  976.  * Set the activity of a file parameter.
  977.  * @param v the vars to use.
  978.  * @param parameter the name of the parameter.
  979.  * @param active the activity status to set (should be set to
  980.  * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).
  981.  */
  982. extern void stp_set_file_parameter_active(const stp_vars_t *v,
  983.                       const char *parameter,
  984.                       stp_parameter_activity_t active);
  985.  
  986. /**
  987.  * Set the activity of a float parameter.
  988.  * @param v the vars to use.
  989.  * @param parameter the name of the parameter.
  990.  * @param active the activity status to set (should be set to
  991.  * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).
  992.  */
  993. extern void stp_set_float_parameter_active(const stp_vars_t *v,
  994.                      const char *parameter,
  995.                      stp_parameter_activity_t active);
  996.  
  997. /**
  998.  * Set the activity of an integer parameter.
  999.  * @param v the vars to use.
  1000.  * @param parameter the name of the parameter.
  1001.  * @param active the activity status to set (should be set to
  1002.  * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).
  1003.  */
  1004. extern void stp_set_int_parameter_active(const stp_vars_t *v,
  1005.                      const char *parameter,
  1006.                      stp_parameter_activity_t active);
  1007.  
  1008. /**
  1009.  * Set the activity of a dimension parameter.
  1010.  * @param v the vars to use.
  1011.  * @param parameter the name of the parameter.
  1012.  * @param active the activity status to set (should be set to
  1013.  * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).
  1014.  */
  1015. extern void stp_set_dimension_parameter_active(const stp_vars_t *v,
  1016.                            const char *parameter,
  1017.                            stp_parameter_activity_t active);
  1018.  
  1019. /**
  1020.  * Set the activity of a boolean parameter.
  1021.  * @param v the vars to use.
  1022.  * @param parameter the name of the parameter.
  1023.  * @param active the activity status to set (should be set to
  1024.  * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).
  1025.  */
  1026. extern void stp_set_boolean_parameter_active(const stp_vars_t *v,
  1027.                          const char *parameter,
  1028.                          stp_parameter_activity_t active);
  1029.  
  1030. /**
  1031.  * Set the activity of a curveparameter.
  1032.  * @param v the vars to use.
  1033.  * @param parameter the name of the parameter.
  1034.  * @param active the activity status to set (should be set to
  1035.  * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).
  1036.  */
  1037. extern void stp_set_curve_parameter_active(const stp_vars_t *v,
  1038.                        const char *parameter,
  1039.                        stp_parameter_activity_t active);
  1040.  
  1041. /**
  1042.  * Set the activity of an array parameter.
  1043.  * @param v the vars to use.
  1044.  * @param parameter the name of the parameter.
  1045.  * @param active the activity status to set (should be set to
  1046.  * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).
  1047.  */
  1048. extern void stp_set_array_parameter_active(const stp_vars_t *v,
  1049.                        const char *parameter,
  1050.                        stp_parameter_activity_t active);
  1051.  
  1052. /**
  1053.  * Set the activity of a raw parameter.
  1054.  * @param v the vars to use.
  1055.  * @param parameter the name of the parameter.
  1056.  * @param active the activity status to set (should be set to
  1057.  * STP_PARAMETER_ACTIVE or STP_PARAMETER_INACTIVE).
  1058.  */
  1059. extern void stp_set_raw_parameter_active(const stp_vars_t *v,
  1060.                      const char *parameter,
  1061.                      stp_parameter_activity_t active);
  1062.  
  1063. /**
  1064.  * Check if a string parameter is set.
  1065.  * @param v the vars to use.
  1066.  * @param parameter the name of the parameter.
  1067.  * @param active the minimum activity status.
  1068.  */
  1069. extern int stp_check_string_parameter(const stp_vars_t *v, const char *parameter,
  1070.                       stp_parameter_activity_t active);
  1071.  
  1072. /**
  1073.  * Check if a file parameter is set.
  1074.  * @param v the vars to use.
  1075.  * @param parameter the name of the parameter.
  1076.  * @param active the minimum activity status.
  1077.  */
  1078. extern int stp_check_file_parameter(const stp_vars_t *v, const char *parameter,
  1079.                     stp_parameter_activity_t active);
  1080.  
  1081. /**
  1082.  * Check if a float parameter is set.
  1083.  * @param v the vars to use.
  1084.  * @param parameter the name of the parameter.
  1085.  * @param active the minimum activity status.
  1086.  */
  1087. extern int stp_check_float_parameter(const stp_vars_t *v, const char *parameter,
  1088.                      stp_parameter_activity_t active);
  1089.  
  1090. /**
  1091.  * Check if an integer parameter is set.
  1092.  * @param v the vars to use.
  1093.  * @param parameter the name of the parameter.
  1094.  * @param active the minimum activity status.
  1095.  */
  1096. extern int stp_check_int_parameter(const stp_vars_t *v, const char *parameter,
  1097.                    stp_parameter_activity_t active);
  1098.  
  1099. /**
  1100.  * Check if a dimension parameter is set.
  1101.  * @param v the vars to use.
  1102.  * @param parameter the name of the parameter.
  1103.  * @param active the minimum activity status.
  1104.  */
  1105. extern int stp_check_dimension_parameter(const stp_vars_t *v, const char *parameter,
  1106.                      stp_parameter_activity_t active);
  1107.  
  1108. /**
  1109.  * Check if a boolean parameter is set.
  1110.  * @param v the vars to use.
  1111.  * @param parameter the name of the parameter.
  1112.  * @param active the minimum activity status.
  1113.  */
  1114. extern int stp_check_boolean_parameter(const stp_vars_t *v, const char *parameter,
  1115.                        stp_parameter_activity_t active);
  1116.  
  1117. /**
  1118.  * Check if a curve parameter is set.
  1119.  * @param v the vars to use.
  1120.  * @param parameter the name of the parameter.
  1121.  * @param active the minimum activity status.
  1122.  */
  1123. extern int stp_check_curve_parameter(const stp_vars_t *v, const char *parameter,
  1124.                      stp_parameter_activity_t active);
  1125.  
  1126. /**
  1127.  * Check if an array parameter is set.
  1128.  * @param v the vars to use.
  1129.  * @param parameter the name of the parameter.
  1130.  * @param active the minimum activity status.
  1131.  */
  1132. extern int stp_check_array_parameter(const stp_vars_t *v, const char *parameter,
  1133.                      stp_parameter_activity_t active);
  1134.  
  1135. /**
  1136.  * Check if a raw parameter is set.
  1137.  * @param v the vars to use.
  1138.  * @param parameter the name of the parameter.
  1139.  * @param active the minimum activity status.
  1140.  */
  1141. extern int stp_check_raw_parameter(const stp_vars_t *v, const char *parameter,
  1142.                    stp_parameter_activity_t active);
  1143.  
  1144. /**
  1145.  * Get the activity status of a string parameter.
  1146.  * @param v the vars to use.
  1147.  * @param parameter the name of the parameter.
  1148.  * @returns the activity status.
  1149.  */
  1150. extern stp_parameter_activity_t
  1151. stp_get_string_parameter_active(const stp_vars_t *v, const char *parameter);
  1152.  
  1153. /**
  1154.  * Get the activity status of a file parameter.
  1155.  * @param v the vars to use.
  1156.  * @param parameter the name of the parameter.
  1157.  * @returns the activity status.
  1158.  */
  1159. extern stp_parameter_activity_t
  1160. stp_get_file_parameter_active(const stp_vars_t *v, const char *parameter);
  1161.  
  1162. /**
  1163.  * Get the activity status of a float parameter.
  1164.  * @param v the vars to use.
  1165.  * @param parameter the name of the parameter.
  1166.  * @returns the activity status.
  1167.  */
  1168. extern stp_parameter_activity_t
  1169. stp_get_float_parameter_active(const stp_vars_t *v, const char *parameter);
  1170.  
  1171. /**
  1172.  * Get the activity status of an integer parameter.
  1173.  * @param v the vars to use.
  1174.  * @param parameter the name of the parameter.
  1175.  * @returns the activity status.
  1176.  */
  1177. extern stp_parameter_activity_t
  1178. stp_get_int_parameter_active(const stp_vars_t *v, const char *parameter);
  1179.  
  1180. /**
  1181.  * Get the activity status of a dimension parameter.
  1182.  * @param v the vars to use.
  1183.  * @param parameter the name of the parameter.
  1184.  * @returns the activity status.
  1185.  */
  1186. extern stp_parameter_activity_t
  1187. stp_get_dimension_parameter_active(const stp_vars_t *v, const char *parameter);
  1188.  
  1189. /**
  1190.  * Get the activity status of a boolean parameter.
  1191.  * @param v the vars to use.
  1192.  * @param parameter the name of the parameter.
  1193.  * @returns the activity status.
  1194.  */
  1195. extern stp_parameter_activity_t
  1196. stp_get_boolean_parameter_active(const stp_vars_t *v, const char *parameter);
  1197.  
  1198. /**
  1199.  * Get the activity status of a curve parameter.
  1200.  * @param v the vars to use.
  1201.  * @param parameter the name of the parameter.
  1202.  * @returns the activity status.
  1203.  */
  1204. extern stp_parameter_activity_t
  1205. stp_get_curve_parameter_active(const stp_vars_t *v, const char *parameter);
  1206.  
  1207. /**
  1208.  * Get the activity status of an array parameter.
  1209.  * @param v the vars to use.
  1210.  * @param parameter the name of the parameter.
  1211.  * @returns the activity status.
  1212.  */
  1213. extern stp_parameter_activity_t
  1214. stp_get_array_parameter_active(const stp_vars_t *v, const char *parameter);
  1215.  
  1216. /**
  1217.  * Get the activity status of a raw parameter.
  1218.  * @param v the vars to use.
  1219.  * @param parameter the name of the parameter.
  1220.  * @returns the activity status.
  1221.  */
  1222. extern stp_parameter_activity_t
  1223. stp_get_raw_parameter_active(const stp_vars_t *v, const char *parameter);
  1224.  
  1225.  
  1226.  
  1227. /****************************************************************
  1228. *                                                               *
  1229. * INFORMATIONAL QUERIES                                         *
  1230. *                                                               *
  1231. ****************************************************************/
  1232.  
  1233. /**
  1234.  * Get the media (paper) size.
  1235.  * Retrieve the media size of the media type set in V, expressed in units
  1236.  * of 1/72".  If the media size is invalid, width and height will be set
  1237.  * to -1.  Values of 0 for width or height indicate that the dimension
  1238.  * is variable, so that custom page sizes or roll paper can be used.
  1239.  * In this case, the size limit should be used to determine maximum and
  1240.  * minimum values permitted.
  1241.  * @param v the vars to use.
  1242.  * @param width a pointer to an int to store the media width in.
  1243.  * @param height a pointer to an int to store the media height in.
  1244.  */
  1245. extern void stp_get_media_size(const stp_vars_t *v, int *width, int *height);
  1246.  
  1247. /**
  1248.  * Get the imagable area of the page.
  1249.  * Retrieve the boundaries of the printable area of the page.  In combination
  1250.  * with the media size, this can be used to determine the actual printable
  1251.  * region, which callers can use to place the image precisely.  The
  1252.  * dimensions are relative to the top left of the physical page.
  1253.  *
  1254.  * If a customizable page size is used (see stp_printer_get_media_size),
  1255.  * the actual desired width and/or height must be filled in using
  1256.  * stp_set_page_width and/or stp_set_page_height.  If these are not filled
  1257.  * in, the margins will be returned.
  1258.  *
  1259.  * Returned values may be negative if a printer is capable of full bleed
  1260.  * by printing beyond the physical boundaries of the page.
  1261.  *
  1262.  * If the media size stored in V is invalid, the return values
  1263.  * will be indeterminate.  It is up to the user to specify legal values.
  1264.  * @param v the vars to use.
  1265.  * @param left a pointer to a int to store the left edge in.
  1266.  * @param right a pointer to a int to store the right edge in.
  1267.  * @param bottom a pointer to a int to store the bottom edge in.
  1268.  * @param top a pointer to a int to store the top edge in.
  1269.  */
  1270. extern void stp_get_imageable_area(const stp_vars_t *v, int *left, int *right,
  1271.                    int *bottom, int *top);
  1272.  
  1273. /**
  1274.  * Get the maximum imagable area of the page.
  1275.  * Retrieve the maximum (regardless of settings other than page sise)
  1276.  * boundaries of the printable area of the page.  In combination
  1277.  * with the media size, this can be used to determine the actual printable
  1278.  * region, which callers can use to place the image precisely.  The
  1279.  * dimensions are relative to the top left of the physical page.
  1280.  *
  1281.  * If a customizable page size is used (see stp_printer_get_media_size),
  1282.  * the actual desired width and/or height must be filled in using
  1283.  * stp_set_page_width and/or stp_set_page_height.  If these are not filled
  1284.  * in, the margins will be returned.
  1285.  *
  1286.  * Returned values may be negative if a printer is capable of full bleed
  1287.  * by printing beyond the physical boundaries of the page.
  1288.  *
  1289.  * If the media size stored in V is invalid, the return values
  1290.  * will be indeterminate.  It is up to the user to specify legal values.
  1291.  * @param v the vars to use.
  1292.  * @param left a pointer to a int to store the left edge in.
  1293.  * @param right a pointer to a int to store the right edge in.
  1294.  * @param bottom a pointer to a int to store the bottom edge in.
  1295.  * @param top a pointer to a int to store the top edge in.
  1296.  */
  1297. extern void stp_get_maximum_imageable_area(const stp_vars_t *v, int *left,
  1298.                        int *right, int *bottom, int *top);
  1299.  
  1300. /**
  1301.  * Get the media size limits.
  1302.  * Retrieve the minimum and maximum size limits for custom media sizes
  1303.  * with the current printer settings.
  1304.  * @param v the vars to use.
  1305.  * @param max_width a pointer to a int to store the maximum width in.
  1306.  * @param max_height a pointer to a int to store the maximum height in.
  1307.  * @param min_width a pointer to a int to store the minimum width in.
  1308.  * @param min_height a pointer to a int to store the minimum height in.
  1309.  */
  1310. extern void
  1311. stp_get_size_limit(const stp_vars_t *v, int *max_width, int *max_height,
  1312.            int *min_width, int *min_height);
  1313.  
  1314.  
  1315. /**
  1316.  * Retrieve the printing resolution of the selected resolution.  If the
  1317.  * resolution is invalid, -1 will be returned in both x and y.
  1318.  * @param v the vars to use.
  1319.  * @param x a pointer to a int to store the horizontal resolution in.
  1320.  * @param y a pointer to a int to store the vertical resolution in.
  1321.  */
  1322. extern void stp_describe_resolution(const stp_vars_t *v, int *x, int *y);
  1323.  
  1324. /**
  1325.  * Verify parameters.
  1326.  * Verify that the parameters selected are consistent with those allowed
  1327.  * by the driver.  This must be called prior to printing; failure to do
  1328.  * so will result in printing failing.
  1329.  * @param v the vars to use.
  1330.  * @returns 0 on failure, 1 on success; other status values are reserved.
  1331.  */
  1332. extern int stp_verify(stp_vars_t *v);
  1333.  
  1334. /**
  1335.  * Get default global settings.  The main use of this is to provide a
  1336.  * usable stp_vars_t for purposes of parameter inquiry in the absence
  1337.  * of a specific printer.  This is currently used in a variety of
  1338.  * places to get information on the standard color parameters without
  1339.  * querying a particular printer.
  1340.  * @returns the default settings.
  1341.  */
  1342. extern const stp_vars_t *stp_default_settings(void);
  1343.  
  1344. typedef void *(*stp_copy_data_func_t)(void *);
  1345. typedef void (*stp_free_data_func_t)(void *);
  1346.  
  1347. typedef enum
  1348. {
  1349.   PARAMETER_BAD,
  1350.   PARAMETER_OK,
  1351.   PARAMETER_INACTIVE
  1352. } stp_parameter_verify_t;
  1353.  
  1354. extern void stp_allocate_component_data(stp_vars_t *v,
  1355.                     const char *name,
  1356.                     stp_copy_data_func_t copyfunc,
  1357.                     stp_free_data_func_t freefunc,
  1358.                     void *data);
  1359. extern void stp_destroy_component_data(stp_vars_t *v, const char *name);
  1360.  
  1361. struct stp_compdata;
  1362. typedef struct stp_compdata compdata_t;
  1363.  
  1364. extern void *stp_get_component_data(const stp_vars_t *v, const char *name);
  1365.  
  1366. extern stp_parameter_verify_t stp_verify_parameter(const stp_vars_t *v,
  1367.                            const char *parameter,
  1368.                            int quiet);
  1369. extern int stp_get_verified(const stp_vars_t *v);
  1370. extern void stp_set_verified(stp_vars_t *v, int value);
  1371.  
  1372. extern void stp_copy_options(stp_vars_t *vd, const stp_vars_t *vs);
  1373.  
  1374. extern void
  1375. stp_fill_parameter_settings(stp_parameter_t *desc,
  1376.                 const stp_parameter_t *param);
  1377.  
  1378.   /** @} */
  1379.  
  1380. #ifdef __cplusplus
  1381.   }
  1382. #endif
  1383.  
  1384. #endif /* GUTENPRINT_VARS_H */
  1385. /*
  1386.  * End of "$Id: vars.h,v 1.3.8.1 2007/03/02 12:01:14 rlk Exp $".
  1387.  */
  1388.